Use sound pack metadata and legacy mappings to decide when specific alert keys should be tried, while keeping severity-only packs simple by default.

Constraint: old sound packs should work without users understanding alert-key internals
Rejected: global specific-alert toggle | it made users manage pack internals manually
Confidence: high
Scope-risk: moderate
Directive: keep specific alert sounds decided per selected pack and keep severity-only packs simple
Tested: uv run pytest tests/test_settings_dialog_audio_events.py tests/test_alert_sound_mapper.py tests/test_alert_notification_system.py tests/test_toasted_windows_notifier.py::TestToastedWindowsNotifierSend::test_send_uses_sound_candidates_when_provided tests/test_sound_player.py::TestGetSoundEntry::test_get_sound_entry_for_candidates_falls_back_within_pack tests/test_sound_player.py::TestUserLevelMute tests/test_sound_player.py::TestSoundPackSpecificAlertMode tests/test_soundpack_event_catalog.py -q; uv run ruff check targeted files; uv run ruff format --check targeted files; uv run pyright; git --no-pager diff --check
Not-tested: manual audio playback through the desktop UI

Co-authored-by: OmX <omx@oh-my-codex.dev>

Avoid installing GUI/audio runtime packages during unit-test CI when tests already provide stubs for those imports.

Constraint: PR validation was stuck in dependency installation after filtering only wxPython
Rejected: installing gui_builder and sound_lib in unit CI | they are runtime packages covered by test stubs here
Confidence: medium
Scope-risk: narrow
Directive: keep artifact workflows responsible for real GUI/audio runtime dependency checks
Tested: uv run pytest tests/test_changelog_tools.py tests/test_installer_version_metadata.py tests/test_nuitka_build.py -q; git --no-pager diff --check
Not-tested: GitHub Actions after push

Co-authored-by: OmX <omx@oh-my-codex.dev>

Drop gui_builder from runtime dependency declarations and packaging/test scaffolding because the project no longer imports it.

Constraint: PR CI dependency installation was blocked by unnecessary GUI runtime dependency resolution
Rejected: keeping gui_builder only for historical packaging | no code imports it and the hidden import is stale
Confidence: high
Scope-risk: narrow
Directive: re-add gui_builder only with a concrete import/use site
Tested: rg -n gui_builder . returned no matches; pre-commit run check-yaml --files .github/workflows/ci.yml; .venv\\Scripts\\ruff.exe check tests/conftest.py; .venv\\Scripts\\ruff.exe format --check tests/conftest.py; uv run pytest tests/test_changelog_tools.py tests/test_installer_version_metadata.py tests/test_nuitka_build.py -q; git --no-pager diff --check
Not-tested: GitHub Actions after push

Co-authored-by: OmX <omx@oh-my-codex.dev>

Keep validation independent of wxPython and sound_lib wheels while preserving dialog and package-staging assertions.

Constraint: Linux CI skips wxPython and sound_lib runtime deps to avoid source builds.

Rejected: Reinstalling wxPython or sound_lib in validation | would reintroduce flaky and slow wheel dependency.

Confidence: high

Scope-risk: narrow

Directive: Keep stubs import-spec-compatible when tests use find_spec or patch sys.modules.

Tested: forced CI-style stub pytest cluster; normal targeted pytest cluster; ruff check; ruff format --check; git diff --check.

Not-tested: full GitHub Actions matrix after push pending.

Keep headless validation aligned with current dialog wiring after the latest dev merge.

Constraint: CI skips GUI/audio runtime dependencies and exercises the local wx/sound_lib stubs.

Rejected: Reintroducing GUI runtime deps in validation | that would restore slow or unavailable wheel installs instead of fixing the test seam.

Confidence: high

Scope-risk: narrow

Directive: Keep these GUI tests focused on dialog contracts, not exact historical fixture coordinates.

Tested: CI-style stubbed pytest for location and forecast product dialog tests; ruff check; ruff format --check; git diff --check.

Not-tested: Full GitHub validation after push.

Keep the headless wx test surface class-like so Linux CI can spec StaticBox while recorder fixtures still capture dialog widgets.

Constraint: CI runs without real wxPython and relies on the local wx stub. Rejected: Removing the affected assertions | would hide the accessibility and visibility regression coverage. Confidence: high. Scope-risk: narrow. Tested: uv run ruff format tests/gui/test_location_dialog_zone_info.py; uv run ruff check tests/gui/test_location_dialog_zone_info.py; uv run python -m py_compile tests/gui/test_location_dialog_zone_info.py; uv run pytest tests/gui/test_location_dialog_zone_info.py -q. Not-tested: Linux CI stub path locally because this Windows checkout has real wxPython and skips this module.

Keep the location dialog GUI tests independent from wx globals that may have been mocked by earlier tests in a parallel CI worker.

Constraint: Ubuntu CI runs the full wx-stub suite in parallel, so this fixture must own the controls it exercises.

Rejected: Relying on module-import defaults alone | full-suite workers can mutate wx.ListCtrl and related controls before these tests run.

Confidence: medium

Scope-risk: narrow

Directive: Keep this test fixture self-contained when adding wx controls to EditLocationDialog coverage.

Tested: uv run ruff check tests/gui/test_location_dialog_zone_info.py; uv run python -m py_compile tests/gui/test_location_dialog_zone_info.py; uv run pytest tests/gui/test_location_dialog_zone_info.py -q

Not-tested: Linux wx-stub path locally; Windows environment skips this module when real wxPython is loaded.

Provide wx.GetApp in the shared headless wx stub so alert dialog tests can initialize an app consistently when wxPython is unavailable.

Constraint: Ubuntu validation may run these wx tests against tests/conftest.py's fallback module rather than real wxPython.

Rejected: Patching each alert dialog test fixture | the missing API belongs to the shared wx stub.

Confidence: high

Scope-risk: narrow

Directive: Add common wx application APIs to tests/conftest.py when multiple GUI tests depend on them.

Tested: uv run ruff check tests/conftest.py tests/test_alert_dialog_copy_integration.py tests/test_alert_dialog_dispatch.py tests/gui/test_location_dialog_zone_info.py; uv run pytest tests/test_alert_dialog_copy_integration.py tests/test_alert_dialog_dispatch.py tests/gui/test_location_dialog_zone_info.py -q

Not-tested: Linux wx-stub path locally.

Keep headless Linux wx fallback objects close enough to wx.Frame and wx.Dialog for alert-dialog fixtures to hide, show, bind, focus, and destroy them without requiring wxPython to import successfully.\n\nConstraint: Ubuntu CI exercises alert dialog tests through the shared no-wx fallback module.\nRejected: Patch only the alert dialog fixtures | the shared fallback is the failing boundary and other wx imports rely on it.\nConfidence: medium\nScope-risk: narrow\nDirective: Keep wx fallback methods minimal and test-oriented; do not turn the shared stub into an application simulator.\nTested: uv run ruff check tests\\conftest.py tests\\test_alert_dialog_copy_integration.py tests\\test_alert_dialog_dispatch.py tests\\gui\\test_location_dialog_zone_info.py\nTested: uv run pytest tests\\test_alert_dialog_copy_integration.py tests\\test_alert_dialog_dispatch.py tests\\gui\\test_location_dialog_zone_info.py -q\nNot-tested: Linux no-wx import path locally; delegated to GitHub Actions on PR #681.

Complete the shared no-wx fallback surface used by alert dialog CI tests so dialog styles, text controls, button IDs, and clipboard operations exist on headless Ubuntu.\n\nConstraint: GitHub Actions Linux runners import the fallback wx module for serial alert dialog tests.\nRejected: Skip or weaken alert dialog assertions | the tests are valid and the fallback module was incomplete.\nConfidence: medium\nScope-risk: narrow\nDirective: Keep clipboard behavior deterministic and limited to text payload tests.\nTested: uv run ruff check tests\\conftest.py tests\\test_alert_dialog_copy_integration.py tests\\test_alert_dialog_dispatch.py tests\\gui\\test_location_dialog_zone_info.py\nTested: uv run pytest tests\\test_alert_dialog_copy_integration.py tests\\test_alert_dialog_dispatch.py tests\\gui\\test_location_dialog_zone_info.py -q\nNot-tested: Linux no-wx import path locally; delegated to GitHub Actions on PR #681.

Preserve fallback wx control ids, labels, and values so headless alert dialog tests can assert real dialog state instead of MagicMock return values.

Constraint: Ubuntu CI exercises serial alert dialog tests through the shared no-wx fallback module.

Rejected: Relax alert dialog assertions | the tests cover valid UI state and only the fallback controls were too generic.

Confidence: medium

Scope-risk: narrow

Directive: Keep control stubs limited to constructor state and simple accessors needed by tests.

Tested: uv run ruff check tests\\conftest.py tests\\test_alert_dialog_copy_integration.py tests\\test_alert_dialog_dispatch.py tests\\gui\\test_location_dialog_zone_info.py

Tested: uv run pytest tests\\test_alert_dialog_copy_integration.py tests\\test_alert_dialog_dispatch.py tests\\gui\\test_location_dialog_zone_info.py -q

Not-tested: Linux no-wx import path locally; delegated to GitHub Actions on PR #681.

Keep fallback wx controls stateful even when tests monkeypatch shared wx base constructors.

Constraint: Ubuntu CI exercises the no-wx fallback while GUI tests patch base widget initialization.

Rejected: Special-case advanced text product tests | the fallback controls should keep their own minimal state consistently.

Confidence: medium

Scope-risk: narrow

Directive: Do not make fallback controls depend on patched base constructor side effects.

Tested: uv run ruff check tests\\conftest.py tests\\gui\\test_advanced_text_product_dialog.py tests\\test_alert_dialog_copy_integration.py tests\\test_alert_dialog_dispatch.py tests\\gui\\test_location_dialog_zone_info.py

Tested: uv run pytest tests\\gui\\test_advanced_text_product_dialog.py tests\\test_alert_dialog_copy_integration.py tests\\test_alert_dialog_dispatch.py tests\\gui\\test_location_dialog_zone_info.py -q

Not-tested: Linux no-wx import path locally; delegated to GitHub Actions on PR #681.

Exercise the no-wx fallback locally and keep fallback controls both stateful and mock-compatible for GUI dialog tests.

Constraint: Ubuntu CI runs without wxPython while this Windows workspace has wxPython installed, hiding fallback-only failures unless forced.

Rejected: Continue patching one missing shim behavior per CI run | a forced fallback gate gives local coverage for the same surface.

Confidence: high

Scope-risk: narrow

Directive: Use ACCESSIWEATHER_FORCE_WX_STUB=1 when changing wx fallback behavior from a wxPython-equipped machine.

Tested: uv run ruff check tests\\conftest.py tests\\gui\\test_advanced_text_product_dialog.py tests\\test_alert_dialog_copy_integration.py tests\\test_alert_dialog_dispatch.py tests\\gui\\test_location_dialog_zone_info.py

Tested: ACCESSIWEATHER_FORCE_WX_STUB=1 uv run pytest tests\\gui\\test_advanced_text_product_dialog.py tests\\test_alert_dialog_copy_integration.py tests\\test_alert_dialog_dispatch.py tests\\gui\\test_location_dialog_zone_info.py -q

Not-tested: Full Ubuntu matrix locally; delegated to GitHub Actions on PR #681.